Overview

This section of the documentation is meant for new Realm-contributors, and should be read in it’s entirety before submitting your first PR. Below you can learn more about our testing & documentation requirements, project layout, and some of the internals of our codebase.

Contribution Guidelines

Documentation

Realm is under heavy active development and documentation can go stale quickly if it’s not actively maintained. Please take a moment to familiarize yourself with both the Developer Documentation you’re reading now as well as the User-Facing Documentation. When submitting a code change, please include updates to the relevant portions of our documentation.

We will do our best during code review to catch changes that require documentation updates, but sometimes things will slip by. If you notice a discrepancy between our codebase and the documentation, please kindly file an issue to track it or submit a PR to correct it. You can use the “Edit this page” feature in the right navbar of the documentation to quickly navigate to the appropriate section of documentation that requires an update.

Testing

Realm contains code across a variety of languages and frameworks. Testing helps ensure our codebase remains stable, enables us to refactor and develop new features with confidence, and can help new Realm developers understand the expected behavior of our code. Below is an outline of the testing requirements for each portion of the codebase, as well as guidance on testing best practices.

Eldritch

Any methods added to the Eldritch Standard Library should have tests collocated in the method’s <name>_impl.rs file. Here are a few things to keep in mind:

  • Tests should be cross platform

Tavern

Tavern Tests (Golang)

All code changes to Tavern must be tested. Below are some standards for test writing that can help improve your PRs:

  • Please submit relevant tests in the same PR as your code change
  • For GraphQL API Tests, please refer to our YAML specification
  • For gRPC API Tests, please refer to our YAML specification
  • Conventionally, please colocate your test code with the code it is testing and include it in the <packagename>_test package
  • We rely on the standard testify assert & require libraries for ensuring expected values (or errors) are returned
  • To enable a variety of inputs for a test case, we rely on closure-driven testing for Golang, you can read more about it here
  • Reusable test code should go in a sub-package suffixed with test
    • For example, reusable test code for the ent package would be located in the ent/enttest package
    • This convention is even used in the Golang standard library (e.g. net/http)
  • Please use existing tests as a reference for writing new tests
Tavern Tests (Front End)

At the time of writing, the Tavern UI is still in an early stage, and therefore minimal testing exists for it. Once the UI is considered more stable, this documentation will be updated. If the Tavern UI is useable and this documentation still exists, please file an issue.

Linear History

In an attempt to reduce the complexity of merges, we enforce a linear history for Realm. This means that when your PR is merged, a “squash & merge” will be enforced so that only one commit is added onto the main branch. This means you can feel free to commit and push as often as you’d like, since all of your commits will be combined before merging your final changes.

Project Structure

  • .devcontainer contains settings required for configuring a VSCode dev container that can be used for Realm development
  • .github contains GitHub related actions, issue templates, etc
  • docker docker containers for production builds
  • docs contains the Jekyll code for the documentation site that you’re reading now!
  • implants is the parent folder of any implant executables or libraries
  • tavern is the parent folder of Tavern related code and packages, and stores the main.go executable for the service
  • terraform contains the Terraform used to deploy a production ready Realm instance. See Tavern User Guide to learn how to use.
  • tests miscellaneous files and example code used for testing. Generally won’t be used but required for some niche situations like deadlocking cargo build.
  • vscode contains our Eldritch VSCode integration source code (Unmaintained)

Where to Start?

If you’d like to make a contribution to Realm but aren’t sure where to start or what features could use help, please consult our Good First Issues for some starting ideas.